home *** CD-ROM | disk | FTP | other *** search
/ Sprite 1984 - 1993 / Sprite 1984 - 1993.iso / man / lib.fmt / tclx / Handles.man < prev    next >
Encoding:
Text File  |  1992-04-23  |  8.1 KB  |  199 lines
  1.  
  2.  
  3.  
  4. Handles               C Library Procedures                Handles
  5.  
  6.  
  7.  
  8. _________________________________________________________________
  9.  
  10. NNAAMMEE
  11.      Tcl_HandleAlloc,     Tcl_HandleFree,      Tcl_HandleTblInit,
  12.      Tcl_HandleTblRelease,  Tcl_HandleTblUseCount Tcl_HandleWalk,
  13.      Tcl_HandleXlate - Dynamic, handle addressable tables.
  14.  
  15.  
  16. SSYYNNOOPPSSIISS
  17.      ##iinncclluuddee <<ttccllEExxtteenndd..hh>>
  18.  
  19.      void_pt
  20.      TTccll__HHaannddlleeTTbbllIInniitt (_h_a_n_d_l_e_B_a_s_e, _e_n_t_r_y_S_i_z_e, _i_n_i_t_E_n_t_r_i_e_s)
  21.  
  22.      int
  23.      TTccll__HHaannddlleeTTbbllUUsseeCCoouunntt (_h_e_a_d_e_r_P_t_r, _a_m_o_u_n_t)
  24.  
  25.      void
  26.      TTccll__HHaannddlleeTTbbllRReelleeaassee (_h_e_a_d_e_r_P_t_r)
  27.  
  28.      void_pt
  29.      TTccll__HHaannddlleeAAlllloocc (_h_e_a_d_e_r_P_t_r, _h_a_n_d_l_e_P_t_r)
  30.  
  31.      void
  32.      TTccll__HHaannddlleeFFrreeee (_h_e_a_d_e_r_P_t_r, _e_n_t_r_y_P_t_r)
  33.  
  34.      void_pt
  35.      TTccll__HHaannddlleeWWaallkk (_h_e_a_d_e_r_P_t_r, _w_a_l_k_K_e_y_P_t_r)
  36.  
  37.      void
  38.      TTccll__WWaallkkKKeeyyTTooHHaannddllee (_h_e_a_d_e_r_P_t_r, _w_a_l_k_K_e_y, _h_a_n_d_l_e_P_t_r)
  39.  
  40.      void_pt
  41.      TTccll__HHaannddlleeXXllaattee (_i_n_t_e_r_p, _h_e_a_d_e_r_P_t_r, _h_a_n_d_l_e)
  42.  
  43. AARRGGUUMMEENNTTSS
  44.      char         *_h_a_n_d_l_e_B_a_s_e   (in)      Base name for the  han-
  45.                                           dle,    numeric   entry
  46.                                           number     will      be
  47.                                           appended.
  48.  
  49.      int          _e_n_t_r_y_S_i_z_e     (in)      Size   of   the   table
  50.                                           entries, in bytes.
  51.  
  52.      int          _i_n_i_t_E_n_t_r_i_e_s   (in)      Initial    number    of
  53.                                           entries to allocate.
  54.  
  55.      int          _a_m_o_u_n_t        (in)      Amount to alter the use
  56.                                           count by.
  57.  
  58.      void_pt      _h_e_a_d_e_r_P_t_r     (in)      Pointer to the header.
  59.  
  60.  
  61.  
  62.  
  63. Sprite v1.0                                                     1
  64.  
  65.  
  66.  
  67.  
  68.  
  69.  
  70. Handles               C Library Procedures                Handles
  71.  
  72.  
  73.  
  74.      char         *_h_a_n_d_l_e_P_t_r    (out)     The  handle   name   is
  75.                                           returned here.  It must
  76.                                           be large enough to hold
  77.                                           the  handle  base  name
  78.                                           with a number appended.
  79.  
  80.      Tcl_Interp   *_i_n_t_e_r_p       (in)      Interpreter to use  for
  81.                                           error reporting.
  82.  
  83.      char         *_h_a_n_d_l_e       (in)      Name   of   handle   to
  84.                                           operate on.
  85.  
  86.      void_pt      _e_n_t_r_y_P_t_r      (in)      Pointer  to  a   handle
  87.                                           table entry.
  88.  
  89.      int          *_w_a_l_k_K_e_y_P_t_r   (i/o)     Key used  to  walk  the
  90.                                           table, initialize to -1
  91.                                           before the first call.
  92.  
  93.      int          _w_a_l_k_K_e_y       (in)      Key returned from walk-
  94.                                           ing the table.
  95. _________________________________________________________________
  96.  
  97.  
  98. DDEESSCCRRIIPPTTIIOONN
  99.      The Tcl handle facility  provides  a  way  to  manage  table
  100.      entries  that may be referenced by a textual handle from Tcl
  101.      code.  This is provided for applications that need to create
  102.      data  structures  in  one  command, return a reference (i.e.
  103.      pointer) to that particular data structure and  then  access
  104.      that  data  structure in other commands. An example applica-
  105.      tion is file handles.
  106.  
  107.      A handle consists of a base  name,  which  is  some  unique,
  108.      meaningful name, such as `ffiillee' and a numeric value appended
  109.      to the base name (e.g. `file3').   The  handle  facility  is
  110.      designed  to  provide  a standard mechanism for building Tcl
  111.      commands that allocate and access table entries based on  an
  112.      entry  index.   The  tables are expanded when needed, conse-
  113.      quently pointers to entries should not be kept, as they will
  114.      become  invalid  when  the  table is expanded.  If the table
  115.      entries are large or pointers must be kept to  the  entries,
  116.      then  the  the  entries  should  be allocated separately and
  117.      pointers kept in the handle table.  A use count is  kept  on
  118.      the  table.   This use count is intended to determine when a
  119.      table shared by multiple commands is to be release.
  120.  
  121.      TTccll__HHaannddlleeTTbbllIInniitt creates and initialize a Tcl dynamic  han-
  122.      dle  table.  The specified initial number of entries will be
  123.      allocated and added to the free list.  The use count will be
  124.      set to one.
  125.  
  126.  
  127.  
  128.  
  129. Sprite v1.0                                                     2
  130.  
  131.  
  132.  
  133.  
  134.  
  135.  
  136. Handles               C Library Procedures                Handles
  137.  
  138.  
  139.  
  140.      TTccll__HHaannddlleeTTbbllUUsseeCCoouunntt alters the use count on  a  table  and
  141.      returns  the  new  value.  The use count has _a_m_o_u_n_t added to
  142.      it, where _a_m_o_u_n_t may be positive, zero or negative.  A  zero
  143.      value  retrieves  the  current  use count.  This is normally
  144.      used to increment the use count when multiple  commands  are
  145.      sharing the table.
  146.  
  147.      TTccll__HHaannddlleeTTbbllRReelleeaassee decrements the use count on a table. If
  148.      it  becomes  zero  (or  negative),  the  the  table  will be
  149.      released. Note that no clean up is done on the  table  entry
  150.      client  supplied  data.   If  clean  up  must  be done, then
  151.      TTccll__HHaannddlleeTTbbllUUsseeCCoouunntt can  be  used  to  decrement  the  use
  152.      count.   When  it  goes to zero, the table may be walked and
  153.      then released.  _H_e_a_d_e_r_P_t_r is declared as CClliieennttDDaattaa so  that
  154.      the procedure may be passed as a command deletion procedure.
  155.  
  156.      TTccll__HHaannddlleeAAlllloocc allocates an entry and associates  a  handle
  157.      with it.  The handle is returned to the buffer pointed to by
  158.      _h_a_n_d_l_e_P_t_r can then be used to access the entry.  The  buffer
  159.      must  be  large  enough  to accommodate the base handle name
  160.      with 2 to 4 digits appended along with  a  terminating  null
  161.      byte.   A  pointer  is  returned to the allocated entry.  If
  162.      TTccll__HHaannddlleeFFrreeee has not  been  called  since  initialization,
  163.      handles  will  be  handed  out sequentially from zero.  This
  164.      behavior is useful in setting up initial  entries,  such  as
  165.      ``ssttddiinn'' for a file table.
  166.  
  167.      TTccll__HHaannddlleeXXllaattee translates a handle  to  a  pointer  to  the
  168.      corresponding  table  entry.  If the handle is not allocated
  169.      (open) or is invalid, NULL is returned and an error  message
  170.      is set in _i_n_t_e_r_p->_r_e_s_u_l_t.
  171.  
  172.      TTccll__HHaannddlleeWWaallkk walks through and finds every allocated entry
  173.      in  a  table.  Entries may be deallocated during a walk, but
  174.      should not  be  allocated.   TTccll__HHaannddlleeWWaallkk  will  return  a
  175.      pointer  to the entry, or NULL if no more entries are avail-
  176.      able.  The integer pointed to by wwaallkkKKeeyyPPttrr should be set to
  177.      `-1'  before  the first call, and then the pointer passed to
  178.      each subsequent call left unmodified.
  179.  
  180.      TTccll__WWaallkkKKeeyyTTooHHaannddllee converts a walk key, as returned from  a
  181.      call to TTccll__HHaannddlleeWWaallkk into a handle.
  182.  
  183.      TTccll__HHaannddlleeFFrreeee frees a handle table entry.
  184.  
  185. KKEEYYWWOORRDDSS
  186.      handle, table, allocate
  187.  
  188.  
  189.  
  190.  
  191.  
  192.  
  193.  
  194.  
  195. Sprite v1.0                                                     3
  196.  
  197.  
  198.  
  199.